home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / p4 / p4-1_2c.lha / p4-1.2c / usc / README_USC < prev    next >
Text File  |  1993-05-24  |  4KB  |  115 lines
  1.  --------------------------------------------------------------------
  2.  | README (Summary documentation for the Microsecond Clock package) |
  3.  |                                                                  |
  4.  | This file briefly describes the functionality  and the user      |
  5.  | interface for the USC system.                                    |
  6.  |                                                                  |
  7.  | Written by:  Arun Nanda    (07/17/91)                            |
  8.  |                                                                  |
  9.  --------------------------------------------------------------------
  10.  
  11. This directory contains the source files for the Microsecond Clock
  12. package (USC).
  13.  
  14. The machine classes that are supported are those that have a hardware
  15. clock available with at least 1 microsecond resolution.  In that case,
  16. true microsecond resolution is obtained.  For other machines (like SUN),
  17. any real-time clock that is available (e.g. gettimeofday) is used and
  18. scaled to a microsecond value.  Thus, the clock value returned on such 
  19. machines will not yield true microsecond resolution.
  20.  
  21.  
  22. CLOCK DATA TYPE
  23. ===============
  24.  
  25. For the purpose of maintaining portability of an application across a
  26. range of architectures, a machine independent data type, denoted by
  27. "usc_time_t", has been defined in the USC package.  The current clock
  28. value and the clock rollover point (see below) are returned as data type
  29. usc_time_t.  Hence, all variables within an user application used to
  30. store and manipulate microsecond clock values must be declared as type
  31. "usc_time_t".
  32.  
  33.  
  34. MICROSECOND CLOCK INTERFACE
  35. ===========================
  36.  
  37. The package comprises of the following macros/functions that are
  38. provided via the include file "usc.h" and the object module "usc.o".
  39.  
  40.     usc_init()        :  (with no parameters)
  41.                  This function must be called exactly once
  42.                  at the beginning before the microsecond
  43.                  clock can be used.
  44.  
  45.     usc_clock()       :  (with no parameters)
  46.                  This function returns the current value of
  47.                  the microsecond clock as a data item of
  48.                  type "usc_time_t".  The microsecond clock
  49.                  is a free running counter that rolls over
  50.                  after the maximum value which is machine
  51.                  dependent.  No assumptions should be made
  52.                  about what the rollover point for a given
  53.                  machine is.  Instead, the generic macro
  54.                  usc_rollover_val() should used to determine
  55.                  this value.
  56.  
  57.     usc_rollover_val():  (with no parameters)
  58.                  This macro is a generic interface to obtain
  59.                  the maximum value that the microsecond
  60.                  clock can take before rolling over to begin
  61.                  a new cycle.  This macro must always be used 
  62.                  to determine the clock rollover point.
  63.  
  64. An application that uses the USC functional interface must do the
  65. following:
  66.  
  67.  1) Include the file "usc.h" at the beginning of the program.
  68.  2) Link the application with the object module "usc.o" and the machine-
  69.     specific library mentioned below.
  70.  
  71.  
  72. INCLUDE FILE
  73. ============
  74.  
  75.     usc.h
  76.  
  77.  
  78. OBJECT FILE TO LINK
  79. ===================
  80.  
  81.     usc.o
  82.  
  83.  
  84. ADDITIONAL MACHINE DEPENDENT LIBRARIES
  85. ======================================
  86.  
  87. The application will also have to be linked with the following machine
  88. dependent libraries in order to enable the microsecond clock to function
  89. properly:
  90.  
  91.                  MULTIMAX        -lpp
  92.                  BALANCE         -lseq
  93.                  SYMMETRY        -lseq
  94.  
  95.  
  96. LIST OF MACHINES SUPPORTED
  97. ==========================
  98.  
  99.         ALLIANT
  100.         BALANCE 
  101.         BFLY1 
  102.         BFLY2 
  103.         BFLY2_TCMP 
  104.         DELTA 
  105.         IBM3090
  106.         RS6000 
  107.         IPSC860_HOST 
  108.         IPSC860_NODE 
  109.         MULTIMAX 
  110.         NEXT 
  111.         SGI 
  112.         SUN 
  113.         SYMMETRY 
  114.         TITAN 
  115.